# Format:
# - name: BlaBla    # Human readable hook name. HOOK_BLABLA and hs_blabla.int in the docs are generated from this. Required.
#   id: HOOK_BLABLA # real hook id. Optional.
#   doc: |
#     Hook documentation, markdown format.
#     Can be multiline.
#     Required.
#   filename: override filename (hs_blabla.int), if it doesn't match the generated one. Optional.

- name: ToHit
  id: HOOK_TOHIT
  doc: |
    Runs when Fallout is calculating the chances of an attack striking a target.<br>
    Runs after the hit chance is fully calculated normally, including applying the 95% cap.

    ```
    int     arg0 - The hit chance (capped)
    Critter arg1 - The attacker
    Critter arg2 - The target of the attack
    int     arg3 - The targeted bodypart
    int     arg4 - Source tile (may differ from attacker's tile, when AI is considering potential fire position)
    int     arg5 - Attack Type (see ATKTYPE_* constants)
    int     arg6 - Ranged flag. 1 if the hit chance calculation takes into account the distance to the target. This does not mean the attack is a ranged attack
    int     arg7 - The raw hit chance before applying the cap

    int     ret0 - The new hit chance. The value is limited to the range of -99 to 999
    ```

- name: AfterHitRoll
  id: HOOK_AFTERHITROLL
  doc: |
    Runs after Fallout has decided if an attack will hit or miss.

    ```
    int     arg0 - If the attack will hit: 0 - critical miss, 1 - miss, 2 - hit, 3 - critical hit
    Critter arg1 - The attacker
    Critter arg2 - The target of the attack
    int     arg3 - The bodypart
    int     arg4 - The hit chance

    int     ret0 - Override the hit/miss
    int     ret1 - Override the targeted bodypart
    Critter ret2 - Override the target of the attack
    ```

- name: CalcAPCost
  id: HOOK_CALCAPCOST
  doc: |
    Runs whenever Fallout calculates the AP cost of using an active item in hand (or unarmed attack). Doesn't run for moving.<br>
    Note that the first time a game is loaded, this script doesn't run before the initial interface is drawn, so if the script effects the AP cost of whatever is in the player's hands at the time the wrong AP cost will be shown. It will be fixed the next time the interface is redrawn.<br>
    You can get the weapon object by checking item slot based on attack type (`ATKTYPE_LWEP1`, `ATKTYPE_LWEP2`, etc) and then calling `critter_inven_obj`.

    ```
    Critter arg0 - The critter performing the action
    int     arg1 - Attack Type (see ATKTYPE_* constants)
    int     arg2 - Is aimed attack (1 or 0)
    int     arg3 - The default AP cost
    Item    arg4 - The weapon for which the cost is calculated. If it is 0, the pointer to the weapon can still be obtained by the aforementioned method

    int     ret0 - The new AP cost
    ```

- name: DeathAnim1
  id: HOOK_DEATHANIM1
  doc: |
    Runs before Fallout tries to calculate the death animation. Lets you switch out which weapon Fallout sees.

    Does not run for critters in the knockdown/out state.

    ```
    int     arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed)
    Critter arg1 - The attacker
    Critter arg2 - The target
    int     arg3 - The amount of damage
    int     arg4 - Unused, always -1. Use this if you are using the same procedure for HOOK_DEATHANIM1 and HOOK_DEATHANIM2 (since sfall 4.1/3.8.24)

    int     ret0 - The pid of an object to override the attacking weapon with
    ```

- name: DeathAnim2
  id: HOOK_DEATHANIM2
  doc: |
    Runs after Fallout has calculated the death animation. Lets you set your own custom frame id, so more powerful than `HOOK_DEATHANIM1`, but performs no validation.<br>
    When using `critter_dmg` function, this script will also run. In that case weapon pid will be -1 and attacker will point to an object with `obj_art_fid == 0x20001F5`.

    Does not run for critters in the knockdown/out state.

    ```
    int     arg0 - The pid of the weapon performing the attack. (May be -1 if the attack is unarmed)
    Critter arg1 - The attacker
    Critter arg2 - The target
    int     arg3 - The amount of damage
    int     arg4 - The death anim id calculated by Fallout

    int     ret0 - The death anim id to override with
    ```

- name: CombatDamage
  id: HOOK_COMBATDAMAGE
  filename: hs_subcombatdmg.int
  doc: |
    Runs when:
    1.  Game calculates how much damage each target will get. This includes primary target as well as all extras (explosions and bursts). This happens BEFORE the actual attack animation.
    2.  AI decides whether it is safe to use area attack (burst, grenades), if he might hit friendlies.

    Does not run for misses, or non-combat damage like dynamite explosions.

    ```
    Critter arg0  - The target
    Critter arg1  - The attacker
    int     arg2  - The amount of damage to the target
    int     arg3  - The amount of damage to the attacker
    int     arg4  - The special effect flags for the target (use bwand DAM_* to check specific flags)
    int     arg5  - The special effect flags for the attacker (use bwand DAM_* to check specific flags)
    Item    arg6  - The weapon used in the attack
    int     arg7  - The bodypart that was struck
    int     arg8  - Damage Multiplier (this is divided by 2, so a value of 3 does 1.5x damage, and 8 does 4x damage. Usually it's 2; for critical hits, the value is taken from the critical table; with Silent Death perk and the corresponding attack conditions, the value will be doubled)
    int     arg9 - Number of bullets actually hit the target (1 for melee attacks)
    int     arg10 - The amount of knockback to the target
    int     arg11 - Attack Type (see ATKTYPE_* constants)
    mixed   arg12 - computed attack data (see C_ATTACK_* for offsets and use get/set_object_data functions to get/set the data)

    int     ret0 - The damage to the target
    int     ret1 - The damage to the attacker
    int     ret2 - The special effect flags for the target
    int     ret3 - The special effect flags for the attacker
    int     ret4 - The amount of knockback to the target
    ```

- name: OnDeath
  id: HOOK_ONDEATH
  doc: |
    Runs immediately after a critter dies for any reason. No return values; this is just a convenience for when you need to do something after death for a large number of different critters and don't want to have to script each and every one of them.

    ```
    Critter arg0 - The critter that just died
    ```

- name: FindTarget
  id: HOOK_FINDTARGET
  doc: |
    Runs when the AI is trying to pick a target in combat. Fallout first chooses a list of 4 likely suspects, then normally sorts them in order of weakness/distance/etc depending on the AI caps of the attacker.<br>
    This hook replaces that sorting function, allowing you to sort the targets in some arbitrary way.

    The return values can include critters that weren't in the list of possible targets, but the additional targets may still be discarded later on in the combat turn if they are out of the attackers perception or the chance of a successful hit is too low. The list of possible targets often includes duplicated entries, but this is fixed in sfall 4.2.3/3.8.23.
    Use `set_sfall_return` to give the 4 targets, in order of preference. If you want to specify less than 4 targets, fill in the extra spaces with 0's or pass -1 to skip the return value.

    __NOTE:__ The engine can choose targets by the following criteria:
    1) The nearest enemy to the attacker.
    2) The enemy that attacked the attacker.
    3) The enemy that attacked an NPC from the same team as the attacker.
    4) The enemy that is attacked by an NPC from the same team as the attacker.

    ```
    Critter arg0 - The attacker
    Critter arg1 - A possible target
    Critter arg2 - A possible target
    Critter arg3 - A possible target
    Critter arg4 - A possible target

    Critter ret0 - The first choice of target
    Critter ret1 - The second choice of target
    Critter ret2 - The third choice of target
    Critter ret3 - The fourth choice of target
    ```

- name: UseObjOn
  id: HOOK_USEOBJON
  doc: |
    Runs when:
    1. a critter uses an object on another critter. (Or themselves)
    1. a critter uses an object from inventory screen AND this object does not have "Use" action flag set and it's not active flare or explosive.
    1. player or AI uses any drug

    This is fired before the object is used, and the relevant `use_obj_on` script procedures are run. You can disable default item behavior.

    __NOTE:__ You can't remove and/or destroy this object during the hookscript (game will crash otherwise). To remove it, return 1.

    ```
    Critter arg0 - The target
    Critter arg1 - The user
    int     arg2 - The object used

    int     ret0 - overrides hard-coded handler and selects what should happen with the item (0 - place it back, 1 - remove it, -1 - use engine handler)
    ```

- name: UseObj
  id: HOOK_USEOBJ
  doc: |
    Runs when:
    1. a critter uses an object from inventory which have "Use" action flag set or it's an active flare or dynamite.
    2. player uses an object from main interface

    This is fired before the object is used, and the relevant `use_obj` script procedures are run. You can disable default item behavior.

    __NOTE:__ You can't remove and/or destroy this object during the hookscript (game will crash otherwise). To remove it, return 1.

    ```
    Critter arg0 - The user
    Obj     arg1 - The object used

    int     ret0 - overrides hard-coded handler and selects what should happen with the item (0 - place it back, 1 - remove it, -1 - use engine handler)
    ```

- name: RemoveInvenObj
  id: HOOK_REMOVEINVENOBJ
  doc: |
    Runs when an object is removed from a container or critter's inventory for any reason.

    ```
    Obj     arg0 - the owner that the object is being removed from
    Item    arg1 - the item that is being removed
    int     arg2 - the number of items to remove
    int     arg3 - The reason the object is being removed (see RMOBJ_* constants)
    Obj     arg4 - The destination object when the item is moved to another object, 0 otherwise
    ```

- name: BarterPrice
  id: HOOK_BARTERPRICE
  doc: |
    Runs whenever the value of goods being purchased is calculated.

    NOTE: the hook is executed twice when entering the barter screen or after transaction: the first time is for the player and the second time is for NPC.

    ```
    Critter arg0 - the critter doing the bartering (either dude_obj or inven_dude)
    Critter arg1 - the critter being bartered with
    int     arg2 - the default value of the goods
    Critter arg3 - table of requested goods (being bought from NPC)
    int     arg4 - the number of actual caps in the barter stack (as opposed to goods)
    int     arg5 - the value of all goods being traded before skill modifications
    Critter arg6 - table of offered goods (being sold to NPC)
    int     arg7 - the total cost of the goods offered by the player
    int     arg8 - 1 if the "offers" button was pressed (not for a party member), 0 otherwise
    int     arg9 - 1 if trading with a party member, 0 otherwise

    int     ret0 - the modified value of all of the goods (pass -1 if you just want to modify offered goods)
    int     ret1 - the modified value of all offered goods
    ```

- name: MoveCost
  id: HOOK_MOVECOST
  doc: |
    Runs when calculating the AP cost of movement.

    ```
    Critter arg0 - the critter doing the moving
    int     arg1 - the number of hexes being moved
    int     arg2 - the original AP cost

    int     ret0 - the new AP cost
    ```

- name: Deprecated hooks
  filename: "" # skip
  doc: |
    * `hs_hexmoveblocking.int`
    * `hs_hexaiblocking.int`
    * `hs_hexshootblocking.int`
    * `hs_hexsightblocking.int`

    Run when checking to see if a hex blocks movement or shooting. (or ai-ing, presumably...)

    __NOTE:__ These hook scripts can become very CPU-intensive and you should avoid using them.
    For this reason, these hooks are not thoroughly supported in sfall, and may be removed in future versions.<br>
    If you want to check if some tile or path is blocked, use functions: `obj_blocking_tile`, `obj_blocking_line`, `path_find_to`.<br>
    If you want script to be called every time NPC moves by hex in combat, use `HOOK_MOVECOST` hook.

    ```
    Critter arg0 - the critter doing the moving
    int     arg1 - the tile number being checked
    int     arg2 - the elevation being checked
    int     arg3 - 1 if the hex would normally be blocking

    Obj     ret0 - 0 if the hex doesn't block, or any sort of object pointer if it does
    ```

- name: ItemDamage
  id: HOOK_ITEMDAMAGE
  doc: |
    Runs when retrieving the damage rating of the player's used weapon. (Which may be their fists.)

    ```
    int     arg0 - The default min damage
    int     arg1 - The default max damage
    Item    arg2 - The weapon used (0 if unarmed)
    Critter arg3 - The critter doing the attacking
    int     arg4 - The type of attack
    int     arg5 - non-zero if this is an attack using a melee weapon

    int     ret0 - Either the damage to be used, if ret1 isn't given, or the new minimum damage if it is
    int     ret1 - The new maximum damage
    ```

- name: AmmoCost
  id: HOOK_AMMOCOST
  doc: |
    Runs when calculating ammo cost for a weapon. Doesn't affect damage, only how much ammo is spent.<br>
    By default, a weapon can perform an attack with at least one ammo, regardless of ammo cost calculation.<br>
    To add proper checks for ammo before attacking (hook type 1 `arg3`), set **CheckWeaponAmmoCost=1** in **Misc** section of ddraw.ini.

    __NOTE:__ The return value must be greater than or equal to 0 to be valid.

    ```
    Item    arg0 - The weapon
    int     arg1 - Number of bullets in burst or 1 for single shots
    int     arg2 - The amount of ammo that will be consumed, calculated by the original ammo cost function (this is basically 2 for Super Cattle Prod and Mega Power Fist)
                   NOTE: for hook type 2, this value is the ammo cost per round (default is always 1)
    int     arg3 - Type of hook:
                   0 - when subtracting ammo after single shot attack
                   1 - when checking for "out of ammo" before attack
                   2 - when calculating number of burst rounds
                   3 - when subtracting ammo after burst attack

    int     ret0 - The new amount of ammo to be consumed, or ammo cost per round for hook type 2 (set to 0 for unlimited ammo)
    ```

- name: KeyPress
  id: HOOK_KEYPRESS
  doc: |
    Runs once every time when any key was pressed or released.
    * DX codes: see **dik.h** header or https://kippykip.com/b3ddocs/commands/scancodes.htm
    * [VK codes](http://msdn.microsoft.com/en-us/library/windows/desktop/dd375731%28v=vs.85%29.aspx)

    __NOTE:__ If you want to override a key, the new key DX scancode should be the same for both pressed and released events.

    ```
    int     arg0 - event type: 1 - pressed, 0 - released
    int     arg1 - key DX scancode
    int     arg2 - key VK code (very similar to ASCII codes)

    int     ret0 - overrides the pressed key (a new key DX scancode or 0 for no override)
    ```

- name: MouseClick
  id: HOOK_MOUSECLICK
  doc: |
    Runs once every time when a mouse button was pressed or released.

    ```
    int     arg0 - event type: 1 - pressed, 0 - released
    int     arg1 - button number (0 - left, 1 - right, up to 7)
    ```

- name: UseSkill
  id: HOOK_USESKILL
  doc: |
    Runs when using any skill on any object.

    This is fired before the default handlers are called, which you can override. In this case you should write your own skill use handler entirely, or otherwise nothing will happen (this includes fade in/fade out, time lapsing and messages - all of this can be scripted; to get vanilla text messages - use `message_str_game` along with `sprintf`).
    Suggested use - override First Aid/Doctor skills to buff/nerf them, override Steal skill to disallow observing NPCs inventories in some cases.

    Does not run if the script of the object calls `script_overrides` for using the skill.

    ```
    Critter arg0 - The user critter
    Obj     arg1 - The target object
    int     arg2 - skill being used
    int     arg3 - skill bonus from items such as first aid kits

    int     ret0 - overrides hard-coded handler (-1 - use engine handler, any other value - override; if it is 0, there will be a 10% chance of removing the used medical item)
    ```

- name: Steal
  id: HOOK_STEAL
  doc: |
    Runs when checking an attempt to steal or plant an item in other inventory using Steal skill.

    This is fired before the default handlers are called, which you can override. In this case you MUST provide message of the result to player ("You steal the %s", "You are caught planting the %s", etc.).
    Example message (vanilla behavior):<br>
    `display_msg(sprintf(mstr_skill(570 + (isSuccess != false) + arg3 * 2), obj_name(arg2)));`

    ```
    Critter arg0 - Thief
    Obj     arg1 - The target
    Item    arg2 - The item being stolen/planted
    int     arg3 - 0 when stealing, 1 when planting
    int     arg4 - quantity of the item being stolen/planted

    int     ret0 - overrides hard-coded handler (2 - force fail without closing window, 1 - force success, 0 - force fail, -1 - use engine handler)
    int     ret1 - overrides experience points gained for stealing this item (must be greater than or equal to 0)
    ```

- name: WithinPerception
  id: HOOK_WITHINPRECEPTION
  doc: |
    Runs when checking if one critter sees another critter. This is used in different situations like combat AI. You can override the result.

    __NOTE:__ `obj_can_see_obj` calls this first when deciding if critter can possibly see another critter with regard to perception, lighting, sneak factors.<br>
    If check fails, the end result is false. If check succeeds (e.g. critter is within perception range), another check is made if there is any blocking tile between two critters (which includes stuff like windows, large bushes, barrels, etc.) and if there is - check still fails.<br>
    You can override "within perception" check by returning 0 or 1, OR, as a convenience, you can also override blocking check after the perception check by returning 2 instead. In this case you should add "line of sight" check inside your hook script, otherwise critters will detect you through walls.

    This is fired after the default calculation is made.

    ```
    Critter arg0 - Watcher object
    Obj     arg1 - Target object
    int     arg2 - Result of vanilla function: 1 - within perception range, 0 - otherwise
    int     arg3 - Type of hook:
        1 - when being called from obj_can_see_obj script function
        2 - when being called from obj_can_hear_obj script function (need to set ObjCanHearObjFix=1 in ddraw.ini)
        3 - when AI determines whether it sees a potential target when selecting attack targets
        0 - all other cases

    int     ret0 - overrides the returned result of the function:
                   0 - not in range (can't see)
                   1 - in range (will see if not blocked)
                   2 - forced detection (will see regardless, only used in obj_can_see_obj script function which is called by every critter in the game)
    ```

- name: InventoryMove
  id: HOOK_INVENTORYMOVE
  doc: |
    Runs before moving items between inventory slots in dude interface. You can override the action.

    What you can NOT do with this hook:
    - force moving items to inappropriate slots (like gun in armor slot)
    What you can do:
    - restrict player from using specific weapons or armors
    - add AP costs for all inventory movement including reloading
    - apply or remove some special scripted effects depending on PC's armor

    ```
    int     arg0 - Target slot:
                   0 - main backpack
                   1 - left hand
                   2 - right hand
                   3 - armor slot
                   4 - weapon, when reloading it by dropping ammo
                   5 - container, like bag/backpack
                   6 - dropping on the ground
                   7 - picking up item
                   8 - dropping item on the character portrait
    Item    arg1 - Item being moved
    Item    arg2 - Item being replaced, weapon being reloaded, or container being filled (can be 0)

    int     ret0 - Override setting (-1 - use engine handler, any other value - prevent relocation of item/reloading weapon/picking up item)
    ```

    Notes for the event of dropping items on the ground:
    - the event is called for each item when dropping multiple items from the stack
    - for ammo type items, the number of dropped ammo in a pack can be found by using the `get_weapon_ammo_count` function
    - for the `PID_BOTTLE_CAPS` item, the event is called only once, and the number of dropped units can be found from the value of the `OBJ_DATA_CUR_CHARGES` object field (or with the `get_weapon_ammo_count` function)

- name: InvenWield
  id: HOOK_INVENWIELD
  doc: |
    Runs before causing a critter or the player to wield/unwield an armor or a weapon (except when using the inventory by PC).
    An example usage would be to change critter art depending on armor being used or to dynamically customize weapon animations.

    __NOTE:__ When replacing a previously wielded armor or weapon, the unwielding hook will not be executed.
    If you need to rely on this, try checking if armor/weapon is already equipped when wielding hook is executed.

    ```
    Critter arg0 - critter
    Item    arg1 - item being wielded or unwielded (weapon/armor)
    int     arg2 - slot (INVEN_TYPE_*)
    int     arg3 - 1 when wielding, 0 when unwielding
    int     arg4 - 1 when removing an equipped item from inventory, 0 otherwise

    int     ret0 - overrides hard-coded handler (-1 - use engine handler, any other value - override) - NOT RECOMMENDED
    ```

- name: AdjustFID
  id: HOOK_ADJUSTFID
  doc: |
    Runs after calculating character figure FID on the inventory screen, whenever the game decides that character appearance might change.
    Also happens on other screens, like barter.

    __NOTE:__ FID has following format: `0x0ABBCDDD`, where: `A` - object type, `BB` - animation code (always 0 in this case), `C` - weapon code, `DDD` - FRM index in LST file.

    ```
    int     arg0 - the vanilla FID calculated by the engine according to critter base FID and armor/weapon being used
    int     arg1 - the modified FID calculated by the internal sfall code (like Hero Appearance Mod)

    int     ret0 - overrides the calculated FID with provided value
    ```

- name: CombatTurn
  id: HOOK_COMBATURN
  doc: |
    Runs before and after each turn in combat (for both PC and NPC).

    ```
    int     arg0 - event type:
                   1 - start of turn
                   0 - normal end of turn
                  -1 - combat ends abruptly (by script or by pressing Enter during PC turn)
                  -2 - combat ends normally (hook always runs at the end of combat)
    Critter arg1 - critter doing the turn
    int     arg2 - 1 at the start/end of the player's turn after loading a game saved in combat mode, 0 otherwise

    int     ret0 - pass 1 at the start of turn to skip the turn, pass -1 at the end of turn to force end of combat
    ```

- name: StdProcedure
  id: HOOK_STDPROCEDURE
  doc: |
    Runs before Fallout executes a standard procedure (handler) in any script of any object.
    NOTE: this hook will not be executed for `start`, `critter_p_proc`, `timed_event_p_proc`, and `map_update_p_proc` procedures.

    ```
    int     arg0 - the number of the standard script handler (see *_proc in define.h)
    Obj     arg1 - the object that owns this handler (self_obj)
    Obj     arg2 - the object that called this handler (source_obj, can be 0)
    int     arg3 - always 0 (1 for _END version)
    Obj     arg4 - the object that is acted upon by this handler (target_obj, can be 0)
    int     arg5 - the parameter of this call (fixed_param), useful for combat_proc

    int     ret0 - pass -1 to cancel the execution of the handler
    ```
- name: StdProcedureEnd
  id: HOOK_STDPROCEDURE_END
  filename: hs_stdprocedure.int
  doc: |
    Runs after Fallout executes a standard procedure (handler) in any script of any object.
    NOTE: this hook will not be executed for `start`, `critter_p_proc`, `timed_event_p_proc`, and `map_update_p_proc` procedures.

    ```
    int     arg0 - the number of the standard script handler (see *_proc in define.h)
    Obj     arg1 - the object that owns this handler (self_obj)
    Obj     arg2 - the object that called this handler (source_obj, can be 0)
    int     arg3 - always 1 (procedure end)
    Obj     arg4 - the object that is acted upon by this handler (target_obj, can be 0)
    int     arg5 - the parameter of this call (fixed_param), useful for combat_proc
    ```

- name: CarTravel
  id: HOOK_CARTRAVEL
  doc: |
    Runs continuously during worldmap travel on car.

    ```
    int     arg0 - vanilla car speed (between 3 and 8 "steps")
    int     arg1 - vanilla fuel consumption (100 and below)

    int     ret0 - car speed override (pass -1 if you just want to override fuel consumption)
    int     ret1 - fuel consumption override
    ```

- name: SetGlobalVar
  id: HOOK_SETGLOBALVAR
  doc: |
    Runs when setting the value of a global variable.

    ```
    int     arg0 - the index number of the global variable being set
    int     arg1 - the set value of the global variable

    int     ret0 - overrides the value of the global variable
    ```

- name: RestTimer
  id: HOOK_RESTTIMER
  doc: |
    Runs continuously while the player is resting (using pipboy alarm clock).

    ```
    int     arg0 - the game time in ticks
    int     arg1 - event type: 1 - when the resting ends normally, -1 - when pressing ESC to cancel the timer, 0 - otherwise
    int     arg2 - the hour part of the length of resting time
    int     arg3 - the minute part of the length of resting time

    int     ret0 - pass 1 to interrupt the resting, pass 0 to continue the rest if it was interrupted by pressing ESC key
    ```

- name: GameModeChange
  id: HOOK_GAMEMODECHANGE
  doc: |
    Runs once every time when the game mode was changed, like opening/closing the inventory, character screen, pipboy, etc.

    ```
    int     arg0 - event type: 1 - when the player exits the game, 0 - otherwise
    int     arg1 - the previous game mode
    ```

- name: UseAnimObj
  id: HOOK_USEANIMOBJ
  doc: |
    Runs before playing the "use" (usually "magic hands") animation when a critter uses a scenery/container object on the map, or before walking/running animation if the player is at a distance from the object.

    ```
    Critter arg0 - the critter that uses an object (usually dude_obj)
    Obj     arg1 - the object being used
    int     arg2 - the animation code being used (see ANIM_* in Animcomd.h)

    int     ret0 - overrides the animation code (pass -1 if you want to skip the animation)
    ```

- name: ExplosiveTimer
  id: HOOK_EXPLOSIVETIMER
  doc: |
    Runs after setting the explosive timer. You can override the result.

    ```
    int     arg0 - the time in ticks set in the timer
    Obj     arg1 - the explosive object
    int     arg2 - the result of engine calculation of whether the timer was set successfully: 1 - failure, 2 - success (similar to ROLL_* in Condtion.h)

    int     ret0 - overrides the time of the timer (maximum 18000 ticks)
    int     ret1 - overrides the result of engine calculation: 0/1 - failure, 2/3 - success (similar to ROLL_*), any other value - use engine handler
    ```

- name: DescriptionObj
  id: HOOK_DESCRIPTIONOBJ
  doc: |
    Runs when using the examine action icon to display the description of an object. You can override the description text.
    An example usage would be to add an additional description to the item based on player's stats/skills.

    Does not run if the script of the object overrides the description.

    __NOTE:__ Returning a pointer to the new text received from the `get_string_pointer` function is still valid, but the method is DEPRECATED and is left for backward compatibility only.

    ```
    Obj     arg0 - the object

    String  ret0 - the new description text to use
    ```

- name: UseSkillOn
  id: HOOK_USESKILLON
  doc: |
    Runs before using any skill on any object. Lets you override the critter that uses the skill.

    __NOTE:__ The user critter can't be overridden when using Steal skill.

    ```
    Critter arg0 - the user critter (usually dude_obj)
    Obj     arg1 - the target object/critter
    int     arg2 - skill being used

    int     ret0 - a new critter to override the user critter. Pass -1 to cancel the skill use, pass 0 to skip this return value
    int     ret1 - pass 1 to allow the skill to be used in combat (only for dude_obj or critter being controlled by the player)
    ```

- name: OnExplosion
  id: HOOK_ONEXPLOSION
  doc: |
    Runs when Fallout is checking all the tiles within the explosion radius for targets before an explosion occurs.
    The tile checking will be interrupted when 6 additional targets (critters) are received.

    ```
    int     arg0 - event type: 1 - when checking objects within the explosion radius without causing damage (e.g. the player drops an active explosive), 0 - otherwise
    Critter arg1 - the attacker
    int     arg2 - the tile on which the explosion occurs
    int     arg3 - checked tile within the explosion radius
    Obj     arg4 - first found object on the checked tile as an additional target
    Critter arg5 - the target critter, may be 0 or equal to the attacker
    int     arg6 - 1 when using throwing weapons (e.g. grenades), 0 otherwise

    int     ret0 - overrides the found object on the checked tile, pass 0 to skip the object
    ```

- name: SubCombatDamage
  id: HOOK_SUBCOMBATDAMAGE
  doc: |
    This hook overrides the vanilla damage calculation formula.
    Runs when:
    1. Before the game calculates how much damage each target will get. This includes primary target as well as all extras (explosions and bursts).
    2. AI decides whether it is safe to use area attack (burst, grenades), if he might hit friendlies.

    Does not run for misses, non-combat damage like dynamite explosions, or if one of the damage formulas is selected in ddraw.ini.

    ```
    Critter arg0 - the attacker
    Critter arg1 - the target
    Item    arg2 - the weapon used in the attack
    int     arg3 - attack type (see ATKTYPE_* constants)
    int     arg4 - number of bullets actually hit the target (1 for melee attacks)
    int     arg5 - target's Damage Resistance (DR) value (affected by critical hit effects, perks, traits, and special unarmed attacks)
    int     arg6 - target's Damage Threshold (DT) value (affected by critical hit effects, perks, traits, and special unarmed attacks)
    int     arg7 - bonus ranged damage from the perk
    int     arg8 - damage multiplier (this is divided by 2, so a value of 3 does 1.5x damage, and 8 does 4x damage. Usually it's 2; for critical hits, the value is taken from the critical table; with Silent Death perk and the corresponding attack conditions, the value will be doubled)
    int     arg9 - combat difficulty multiplier (125 - rough, 100 - normal, 75 - wimpy; for player or party members it's always 100)
    int     arg10 - the calculated amount of damage (usually 0, required when using multiple hook scripts to calculate damage and using the set_sfall_arg function)
    mixed   arg11 - computed attack data (see C_ATTACK_* for offsets and use get/set_object_data functions to get/set the data)

    int     ret0 - the returned amount of damage
    ```

- name: SetLighting
  id: HOOK_SETLIGHTING
  doc: |
    Runs before setting the light level for an object or a map. You can override the result.

    ```
    Obj     arg0 - the object being set, or -1 when setting the light level for a map
    int     arg1 - the light intensity
    int     arg2 - the light radius, or -1 when setting the light level for a map

    int     ret0 - overrides the light intensity. Intensity range is from 0 to 65536
    int     ret1 - overrides the light radius. Radius range is from 0 to 8 (works only for the object)
    ```

- name: Sneak
  id: HOOK_SNEAK
  doc: |
    Runs when the Sneak skill is activated, or when the game rolls another Sneak check after the duration for the current one is over.
    You can override the result of a random Sneak check or the duration time for the current result.

    ```
    int     arg0 - Sneak check result: 1 - success, 0 - failure
    int     arg1 - the duration in ticks for the current Sneak check (time depends on Sneak skill level)
    Critter arg2 - the critter (usually dude_obj)

    int     ret0 - overrides the result of the Sneak check
    int     ret1 - overrides the duration time for the current result
    ```

- name: TargetObject
  id: HOOK_TARGETOBJECT
  doc: |
    Runs when the targeting cursor hovers over an object, or when the player tries to attack the target object.
    You can override the target object or prevent the player from attacking the chosen target.

    ```
    int     arg0 - event type: 0 - when the targeting cursor hovers over the object, 1 - when trying to attack the target object
    int     arg1 - 1 when the target object is valid to attack, 0 otherwise
    Obj     arg2 - the target object

    mixed   ret0 - overrides the target object, or pass -1 to prevent the player from attacking the object
    ```

- name: Encounter
  id: HOOK_ENCOUNTER
  doc: |
    Runs whenever a random encounter occurs (except the Horrigan meeting and scripted encounters), or when the player enters a local map from the world map.
    You can override the map for loading or the encounter.

    ```
    int     arg0 - event type: 0 - when a random encounter occurs, 1 - when the player enters from the world map
    int     arg1 - the map ID that the encounter will load (see MAPS.h or Maps.txt)
    int     arg2 - 1 when the encounter occurs is a special encounter, 0 otherwise

    int     ret0 - overrides the map ID, or pass -1 for event type 0 to cancel the encounter and continue traveling
    int     ret1 - pass 1 to cancel the encounter and load the specified map from the ret0 (only for event type 0)
    ```

- name: AdjustPoison
  id: HOOK_ADJUSTPOISON
  doc: |
    Runs when a critter's poison level is changed, or when the player takes damage from the poison.

    ```
    Critter arg0 - the critter
    int     arg1 - the amount of poison being added/removed
    int     arg2 - the damage value at the time of applying the poison effect
                   (damage from the poison effect is implemented only for the player character; for other critters, this value will always be 0)

    int     ret0 - the new amount of poison being added/removed
    int     ret1 - the new damage value, only negative values are allowed (will only be valid at the time of taking damage from the poison)
    ```

- name: AdjustRads
  id: HOOK_ADJUSTRADS
  doc: |
    Runs when a critter's radiation level is changed.

    ```
    Critter arg0 - the critter (usually dude_obj)
    int     arg1 - the amount of radiation being added/removed

    int     ret0 - the new amount of radiation being added/removed
    ```

- name: RollCheck
  id: HOOK_ROLLCHECK
  doc: |
    Runs when a game event performs a random roll to check the chance of success or failure.

    ```
    int     arg0 - event type:
                   1 - checks the chance of an attack hitting the target
                   2 - checks the chance of a bullet from a burst hitting the target (for burst attacks)
                   3 - checks the chance when using skills (not listed below)
                   4 - check the chance of using Repair skill
                   5 - check the chance of using Doctor skill
                   6 - check the chance of using Steal skill for the thief (usually the player)
                   7 - the second Steal skill chance check for the target to catch the thief, in which the target's failure is the thief's success result
    int     arg1 - the value of roll result (see ROLL_* constants), which is calculated as:
                   for ROLL_CRITICAL_SUCCESS: random(1, 100) <= (random_chance / 10) + bonus
                   for ROLL_CRITICAL_FAILURE: random(1, 100) <= -random_chance / 10
    int     arg2 - the chance value
    int     arg3 - the bonus value, used when checking critical success
    int     arg4 - random chance (calculated as: chance - random(1, 100)), where a negative value is a failure check (ROLL_FAILURE)

    int     ret0 - overrides the roll result
    ```

- name: BestWeapon
  id: HOOK_BESTWEAPON
  doc: |
    Runs when the AI decides which weapon is the best while searching the inventory for a weapon to equip in combat.
    This also runs when the player presses the "Use Best Weapon" button on the party member control panel.

    ```
    Critter arg0 - the critter searching for a weapon
    Item    arg1 - the best weapon chosen from two items
    Item    arg2 - the first choice of weapon
    Item    arg3 - the second choice of weapon
    Critter arg4 - the target of the critter (can be 0)

    Item    ret0 - overrides the chosen best weapon
    ```

- name: CanUseWeapon
  id: HOOK_CANUSEWEAPON
  doc: |
    Run when the AI checks whether it can use a weapon.
    This mostly happens when NPCs try to find weapons in their inventory or on the map.

    ```
    Critter arg0 - the critter doing the check
    Item    arg1 - the weapon being checked
    int     arg2 - attack type (see ATKTYPE_* constants)
    int     arg3 - original result of engine function: 1 - can use, 0 - cannot use

    int     ret0 - overrides the result of engine function. Any non-zero value allows using the weapon
    ```
